{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Building Chemical Reaction Networks (CRNs) Directly with BioCRNpyler\n",
    "\n",
    "**Overview:**  This tutorial shows how to use [BioCRNpyler](https://github.com/BuildACell/BioCRNPyler) to represent simple CRNs\n",
    "\n",
    "## What is a CRN?\n",
    "A CRN is a widely established model of chemistry and biochemistry.\n",
    "* A set of species $S$\n",
    "* A set of reactions $R$ interconvert species $I_r$ to $O_r$\n",
    "\\begin{align}\n",
    "\\\\\n",
    "I \\xrightarrow[]{\\rho(s)} O\n",
    "\\\\\n",
    "\\end{align}\n",
    " * $I$ and $O$ are multisets of species $S$. \n",
    " * $\\rho(s): S \\to \\mathbb{R}$ is a function that determines how fast the reaction occurs.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Combining Species and Reactions into a CRN\n",
    "\n",
    "The following code defines a species called 'S' made out of material 'material'. Species can also have attributes to help identify them. Note that Species with the same name, but different materials or attributes are considered different species in terms of the reactions they participate in.\n",
    "\n",
    "    S = Species('name', material_type='material', attributes=[])\n",
    "\n",
    "The collowing code produces a reaction R\n",
    "    \n",
    "    R = Reaction(Inputs, Outputs, k)\n",
    "\n",
    "here `Inputs` and `Outputs` must both be a list of `Species`. The parameter `k` is the rate constant of the reaction. By default, propensities in BioCRNpyler are massa ction:\n",
    "\n",
    "### $\\rho(S) = k \\Pi_{s} s^{I_s}$\n",
    "\n",
    "Note: for stochastic models mass action propensities are $\\rho(S) = k \\Pi_{s} s!/(s - I_s)!$.\n",
    "\n",
    "Mass action reactions can be made reversible with the `k_rev` keyword:\n",
    "\n",
    "    R_reversible = Reaction(Inputs, Outputs, k, k_rev = krev)\n",
    "\n",
    "is the same as two reactions:\n",
    "\n",
    "    R = Reaction(Inputs, Outputs, k)\n",
    "    Rrev = Reaction(Outputs, Inputs, krev)\n",
    "\n",
    "\n",
    "Finally, a CRN can be made by combining species and reactions:\n",
    "\n",
    "    CRN = ChemicalReactionNetwork(species=species, reactions=reactions, initial_condition_dict={})\n",
    "\n",
    "Here, `initial_condition_dict` is an optional dictionary to store the initial values of different species. \n",
    "\n",
    "    initial_condition_dict = {Species: value}\n",
    "\n",
    "Species without an initial condition will default to 0."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Species can be printed to show their string representation: m1_A_attribute m1_B m2_B D\n",
      "\n",
      "Reactions can be printed as well:\n",
      " m1[A(attribute)] --> 2m1[B] \n",
      " m1[B] --> m2[B]+D\n",
      "\n",
      "Directly printing a CRN shows the stringrepresentation of the species used in BioCRNpyler:\n",
      "\n",
      "Species = m1_A_attribute, m1_B, m2_B, D\n",
      "Reactions = [\n",
      "\tm1[A(attribute)] --> 2m1[B]\n",
      "\tm1[B] --> m2[B]+D\n",
      "]\n",
      "\n",
      "CRN.pretty_print(...) is a function that prints a more customizable\n",
      "version of the CRN, but doesn't show the proper string representation of species:\n",
      "\n",
      "Species(N = 4) = {\n",
      "m1[A(attribute)] (@ 10),  D (@ 0),  m2[B] (@ 0),  m1[B] (@ 0),  \n",
      "}\n",
      "\n",
      "Reactions (2) = [\n",
      "0. m1[A(attribute)] --> 2m1[B]\n",
      " Kf=k_forward * m1_A_attribute\n",
      "  k_forward=3.0\n",
      "\n",
      "1. m1[B] --> m2[B]+D\n",
      " Kf=k_forward * m1_B\n",
      "  k_forward=1.4\n",
      "\n",
      "]\n"
     ]
    }
   ],
   "source": [
    "# Import required packages\n",
    "from biocrnpyler import Species, Reaction, ChemicalReactionNetwork\n",
    "\n",
    "# Example: Model the CRN consisting of: A --> 2B,\n",
    "# 2B <--> B + C where C has the same name as B but a new material\n",
    "A = Species(\"A\", material_type = \"m1\", attributes = [\"attribute\"])\n",
    "B = Species(\"B\", material_type = \"m1\")\n",
    "C = Species(\"B\", material_type = \"m2\")\n",
    "D = Species(\"D\")\n",
    "\n",
    "print(\"Species can be printed to show their string representation:\", A, B, C, D)\n",
    "\n",
    "# Reaction Rates\n",
    "k1 = 3.\n",
    "k2 = 1.4\n",
    "k2rev = 0.15\n",
    "\n",
    "# Reaciton Objects\n",
    "R1 = Reaction.from_massaction([A], [B, B], k_forward = k1)\n",
    "R2 = Reaction.from_massaction([B], [C, D], k_forward = k2)\n",
    "\n",
    "print(\"\\nReactions can be printed as well:\\n\", R1,\"\\n\", R2)\n",
    "\n",
    "#create an initial condition so A has a non-zero value\n",
    "initial_concentration_dict = {A:10}\n",
    "\n",
    "# Make a CRN\n",
    "CRN = ChemicalReactionNetwork(species = [A, B, C, D], reactions = [R1, R2],\n",
    "                              initial_concentration_dict = initial_concentration_dict)\n",
    "\n",
    "# CRNs can be printed in two different ways\n",
    "print(\"\\nDirectly printing a CRN shows the string\"\n",
    "      \"representation of the species used in BioCRNpyler:\\n\")\n",
    "print(CRN)\n",
    "\n",
    "print(\"\\nCRN.pretty_print(...) is a function that prints a more customizable\\n\"\n",
    "      \"version of the CRN, but doesn't show the proper string representation of species:\\n\")\n",
    "print(CRN.pretty_print(show_materials = True, show_rates = True, show_attributes = True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## CRNs can be saved as SBML and simulated\n",
    "\n",
    "To save a CRN as SBML:\n",
    "\n",
    "    CRN.write_sbml_file(\"file_name.xml\")\n",
    "\n",
    "To simulate a CRN with bioscrape:\n",
    "\n",
    "    Results, Model = CRN_expression.simulate_with_bioscrape(timepoints, initial_condition_dict=x0)\n",
    "\n",
    "Where x0 is a dictionary: x0 = {species_name: initial_value}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Saving and simulating a CRN\n",
    "CRN.write_sbml_file(\"build_crns_directly.xml\")\n",
    "\n",
    "try:\n",
    "    import bioscrape\n",
    "    import numpy as np\n",
    "    import pylab as plt\n",
    "    import pandas as pd\n",
    "    \n",
    "    # Initial conditions can be set with a dictionary:\n",
    "    x0 = {A:120}\n",
    "    timepoints = np.linspace(0, 1, 100)#Timepoints to simulate over\n",
    "    \n",
    "    # This function can also take a filename keyword to save the file at the same time\n",
    "    R = CRN.simulate_with_bioscrape_via_sbml(timepoints=timepoints, initial_condition_dict=x0)\n",
    "\n",
    "    # Check to ensure simulation worked\n",
    "    # Results are in a Pandas Dictionary and can be accessed via string-names of species\n",
    "    plt.plot(R['time'], R[str(A)], label = \"A\")\n",
    "    plt.plot(R['time'], R[str(B)], label = \"B\")\n",
    "    plt.plot(R['time'], R[str(C)], \"--\", label = \"C\")\n",
    "    plt.plot(R['time'], R[str(D)],\":\", label = \"D\")\n",
    "    plt.xlabel(\"Time\")\n",
    "    plt.ylabel(\"Species concentrations\")\n",
    "    plt.legend()\n",
    "    \n",
    "except ModuleNotFoundError:\n",
    "    print(\"Plotting Modules not installed.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ComplexSpecies and OrderedComplexSpecies\n",
    "\n",
    "When `Species` bind together to form complexes, it is recommended to use the `Complex` function:\n",
    "\n",
    "    from biocrnpyler import Complex\n",
    "    Complex([list of species], ordered = True/False) \n",
    "\n",
    "This function returns the classes ComplexSpecies or OrderedComplexSpecies subclasses which contain information about the species inside of them. ComplexSpecies treats its internal species as an unordered multiset. OrderedComplexSpecies treats its internal species as an ordered list. It is recommended to always use the function Complex to create these types of Species for compatability reasons discussed in the OrderedPolymerSpecies example notebook.\n",
    "\n",
    "_Note: These objects do not automatically generate binding reactions. To do that, use the Component wrappers ChemicalComplex and OrderedChemicalComplex._"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "For ComplexSpecies, the order of the elements does not matter:\n",
      "C1=ComplexSpecies([A, B, B2, A])= complex_m1_A_2x_m1_B_m2_B_\n",
      "C2=ComplexSpecies([B, A, B2, A])= complex_m1_A_2x_m1_B_m2_B_\n",
      "C1==C2 ==> True\n",
      "\n",
      "For OrderedComplexSpecies, the Order Does Matter:\n",
      "C3=OrderedComplexSpecies([A, B, B2, A])= ordered_complex_m1_A_m1_B_m2_B_m1_A_\n",
      "C4=OrderedComplexSpecies([B, A, B2, A])= ordered_complex_m1_B_m1_A_m2_B_m1_A_\n",
      "C3==C4 ==> False\n",
      "\n",
      "ComplexSpecies (and the OrderedComplexSpecies and Multimers) are Species and can be used in reactions:\n",
      "Reaction.from_massaction([A, B, B2, A], [C1], k_forward = 10)=\n",
      "2m1[A]+m1[B]+m2[B] --> complex[2x_m1[A]:m1[B]:m2[B]]\n"
     ]
    }
   ],
   "source": [
    "from biocrnpyler import Complex \n",
    "\n",
    "A = Species(\"A\", material_type = \"m1\")\n",
    "B = Species(\"B\", material_type = \"m1\")\n",
    "B2 = Species(\"B\", material_type = \"m2\")\n",
    "\n",
    "print(\"\\nFor ComplexSpecies, the order of the elements does not matter:\")\n",
    "C1 = Complex([A, B, B2, A])\n",
    "C2 = Complex([B, A, B2, A])\n",
    "print(\"C1=ComplexSpecies([A, B, B2, A])=\", C1)\n",
    "print(\"C2=ComplexSpecies([B, A, B2, A])=\", C2)\n",
    "print(\"C1==C2 ==>\", C1==C2)\n",
    "\n",
    "print(\"\\nFor OrderedComplexSpecies, the Order Does Matter:\")\n",
    "C3 = Complex([A, B, B2, A], ordered = True)\n",
    "C4 = Complex([B, A, B2, A], ordered = True)\n",
    "print(\"C3=OrderedComplexSpecies([A, B, B2, A])=\", C3)\n",
    "print(\"C4=OrderedComplexSpecies([B, A, B2, A])=\", C4)\n",
    "print(\"C3==C4 ==>\", C3==C4)\n",
    "\n",
    "print(\"\\nComplexSpecies (and the OrderedComplexSpecies and Multimers) are Species and can be used in reactions:\")\n",
    "R = Reaction.from_massaction([A, B, B2, A], [C1], k_forward=10)\n",
    "print(\"Reaction.from_massaction([A, B, B2, A], [C1], k_forward = 10)=\")\n",
    "print(R)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Non-mass action propensities in BioCRNpyler\n",
    "By default, BioCRNpyler assumes that propensities are mass action with only one parameter, the rate constant $k_{forward}$ (and optional reverse rate $k_{reverse}$. However, additional propensity types are also supported. These reactions are created in two steps: first a `Propensity` of the appropriate type is made, then a `Reaction` is made using that `Propensity`. These reactions are always created irreversibly. Examples are shown below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## HillPositive: \n",
    "$\\rho(s) = k \\frac{s_1^n}{K^n+s_1^n}$\n",
    "\n",
    "Requried parameters: rate constant $k$, offset $K$, Hill coefficient $n$, and hill species $s_1$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "m1[A] --> m1[B]\n",
      " Kf = k R^n / ( K^n + R^n )\n",
      "  k=1\n",
      "  K=5\n",
      "  n=2\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from biocrnpyler import HillPositive\n",
    "\n",
    "# Create the propensity\n",
    "R = Species(\"R\")\n",
    "hill_pos  = HillPositive(k=1, s1=R, K=5, n=2)\n",
    "\n",
    "# Create the reaction\n",
    "r_hill_pos = Reaction([A], [B], propensity_type = hill_pos)\n",
    "\n",
    "# Print the reaction\n",
    "print(r_hill_pos.pretty_print())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## HillNegative: \n",
    "$\\rho(s) = k \\frac{1}{K^n+s_1^n}$\n",
    "\n",
    "Requried parameters: rate constant $k$, offset $K$, Hill coefficient $n$, and Hill species $s_1$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "m1[A] --> m1[B]\n",
      " Kf = k R^n / ( K^n + R^n )\n",
      "  k=1\n",
      "  K=5\n",
      "  n=2\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Create the propensity\n",
    "R = Species(\"R\")\n",
    "hill_neg  = HillPositive(k=1, s1=R, K=5, n=2)\n",
    "\n",
    "# Create the reaction\n",
    "r_hill_neg = Reaction([A], [B], propensity_type = hill_neg)\n",
    "\n",
    "# Print the reaction\n",
    "print(r_hill_neg.pretty_print())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ProportionalHillPositive: \n",
    "$\\rho(s, d) = k d \\frac{s_1^n}{K^n + s_1^n}$\n",
    "\n",
    "Requried parameters: rate constant $k$, offset $K$, Hill coefficient $n$, Hill species $s_1$, and proportional species $d$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "m1[A] --> m1[B]\n",
      " Kf = k D R^n / ( K^n + R^n )\n",
      "  k=1\n",
      "  K=5\n",
      "  n=2\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from biocrnpyler import ProportionalHillPositive\n",
    "#create the propensity\n",
    "R = Species(\"R\")\n",
    "D = Species(\"D\")\n",
    "prop_hill_pos  = ProportionalHillPositive(k=1, s1=R, K=5, n=2, d=D)\n",
    "\n",
    "# Create the reaction\n",
    "r_prop_hill_pos = Reaction([A], [B], propensity_type=prop_hill_pos)\n",
    "\n",
    "# Print the reaction\n",
    "print(r_prop_hill_pos.pretty_print())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ProportionalHillNegative: \n",
    "$\\rho(s, d) = k d \\frac{1}{K^n + s_1^n}$\n",
    "\n",
    "Requried parameters: rate constant $k$, offset $K$, Hill coefficient $n$, Hill species $s_1$, and proportional species $d$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "m1[A] --> m1[B]\n",
      " Kf = k D / ( 1 + (R/K)^2 )\n",
      "  k=1\n",
      "  K=5\n",
      "  n=2\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from biocrnpyler import ProportionalHillNegative\n",
    "#create the propensity\n",
    "R = Species(\"R\")\n",
    "D = Species(\"D\")\n",
    "prop_hill_neg  = ProportionalHillNegative(k=1, s1=R, K=5, n=2, d=D)\n",
    "\n",
    "#create the reaction\n",
    "r_prop_hill_neg = Reaction([A], [B], propensity_type=prop_hill_neg)\n",
    "\n",
    "#print the reaction\n",
    "print(r_prop_hill_neg.pretty_print())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## General Propensity: \n",
    "$\\rho(s) = $ function of your choice\n",
    "\n",
    "For general propensities, the function must be written out as a string with all species and parameters declared."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "m1[A]+m1[B] --> complex[2x_m1[A]:m1[B]:m2[B]]\n",
      "k1*2 - k2/S^2\n",
      "  k1=1.11\n",
      "  k2=2.22\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from biocrnpyler import ParameterEntry, GeneralPropensity\n",
    "\n",
    "# Create some parameters - note that parameters will be discussed in the next lecture\n",
    "k1 = ParameterEntry(\"k1\", 1.11)\n",
    "k2 = ParameterEntry(\"k2\", 2.22)\n",
    "\n",
    "# Create species\n",
    "S = Species(\"S\")\n",
    "\n",
    "# Type the string as a rate then declare the species and parameters\n",
    "general = GeneralPropensity(f'k1*2 - k2/{S}^2',\n",
    "                            propensity_species=[S],\n",
    "                            propensity_parameters=[k1, k2])\n",
    "\n",
    "r_general = Reaction([A, B], [C1], propensity_type=general)\n",
    "\n",
    "print(r_general.pretty_print())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# End"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}